Creating new docly files

What you'll see

An AI coding agent or script writes a new .docly file into the WebDAV-mounted Docly drive. Either the document does not open in Docly, or the tooling reports the write as failed because the file size on disk does not match what was written. The instinct is to treat the filename as spent and start again under a different name.

What's actually happening

The Docly drive binds a .docly file to its schema when a complete, parseable file appears at the path. It parses the JSON, reads the Schema string, and registers the document. On success it rewrites the file with its own metadata, so the file on disk afterwards is not byte-identical to what you wrote.

Writing straight to the drive path works. Measured 2026-08-25 against a live site: a direct write registers correctly - schema bound, Guid assigned, file re-serialised - both for a 560-byte document and for a 355 KB document carrying two embedded images.

A failed write does not burn the filename. Both plausible failure shapes were tested at the same path, then corrected at that same path:

• Truncated JSON. The file was left on disk exactly as written, unregistered. Writing valid JSON to the same path afterwards registered normally, with a Guid assigned.
• A Schema value naming a schema that does not exist. The document registered and kept that string verbatim - there is no fallback to a generic upload. Rewriting the same path with the correct schema name bound it correctly.

So the reason to get the JSON right is that a document which fails to parse is useless, not that the name is spent.

What to do

Write the file to the drive path. Validate that the JSON parses first - that is the only thing standing between you and a registered document.

Building the file in a temp folder and using Copy-Item to move it into place is still a perfectly good habit and costs nothing, but it is belt-and-braces rather than a requirement.

Minimum file envelope (regardless of schema):

{
  "Document": { /* fields defined by your target schema */ },
  "EmbeddedFiles": [],
  "Schema": "<schema-name>",
  "Tags": [],
  "Modified": "2026-05-15T12:00:00.0000000+02:00",
  "Created": "2026-05-15T12:00:00.0000000+02:00"
}

The drive assigns Guid and overwrites Modified and Created with real timestamps on successful registration - placeholders are fine. ROWIDs inside form chapters are standard UUIDs with dashes; Docly generates them on save, but supplying fresh ones in a programmatically-built file is harmless.

Structural traps that break a document (none of them burn the filename - fix and rewrite the same path):

• A Schema value that does not name a real schema. The document registers with that literal string and therefore binds to nothing and renders as nothing.
• Field names in Document not matching the schema's form fields (case-sensitive). Unlisted fields are dropped silently.
• Enum values stored as user-facing labels instead of internal values (e.g. "By design" instead of "ByDesign"). Internal values come from the schema's Options[].Value, not Options[].Label.
• Form Chapters expected to nest as sub-objects - they flatten. Fields inside a Chapter sit alongside the other Document properties, with one Expand boolean and one ROWID UUID per Chapter added.
• Radio-group fields missing the FieldName__docly_radiogroup duplicate next to FieldName; both carry the same internal value.
• Rich-text fields written as markdown - they are HTML strings, so escape " as \" inside the JSON.
• Hand-rolling the count fields (OKCount, TotalCount, etc.). Docly maintains these on form save; start at "0" or copy from an existing instance.

Verify registration by re-reading and parsing the file:

• A Guid is present, assigned by Docly.
• The file content differs from what you wrote, because the drive re-serialised it.
• The directory listing still shows the .docly suffix.

If the document did not register, correct the JSON and write the same path again.

For the full reference, see Editing Docly documents programmatically.